home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 2003 August / MW 8 2003 CD1.iso / Inside Macworld / Product News / gimp-1.2.4.sit / gimp-1.2.4 / devel-docs / libgimp / sgml / gimpunitmenu.sgml < prev    next >
Encoding:
Text File  |  2003-05-20  |  9.4 KB  |  258 lines
  1. <refentry id="GimpUnitMenu" revision="19 Jan 2001">
  2. <refmeta>
  3. <refentrytitle>GimpUnitMenu</refentrytitle>
  4. <manvolnum>3</manvolnum>
  5. <refmiscinfo>LIBGIMP Library</refmiscinfo>
  6. </refmeta>
  7.  
  8. <refnamediv>
  9. <refname>GimpUnitMenu</refname><refpurpose>Widget for selecting a <link linkend="GimpUnit">GimpUnit</link>.</refpurpose>
  10. </refnamediv>
  11.  
  12. <refsynopsisdiv><title>Synopsis</title>
  13. <synopsis>
  14.  
  15.  
  16.  
  17. struct      <link linkend="GimpUnitMenu-struct">GimpUnitMenu</link>;
  18. #define     <link linkend="GIMP-UNIT-MENU-CAPS">GIMP_UNIT_MENU</link>                  (obj)
  19. <link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gimp-unit-menu-new">gimp_unit_menu_new</link>              (const <link linkend="gchar">gchar</link> *format,
  20.                                              <link linkend="GimpUnit">GimpUnit</link> unit,
  21.                                              <link linkend="gboolean">gboolean</link> show_pixels,
  22.                                              <link linkend="gboolean">gboolean</link> show_percent,
  23.                                              <link linkend="gboolean">gboolean</link> show_custom);
  24. void        <link linkend="gimp-unit-menu-set-unit">gimp_unit_menu_set_unit</link>         (<link linkend="GimpUnitMenu">GimpUnitMenu</link> *gum,
  25.                                              <link linkend="GimpUnit">GimpUnit</link> unit);
  26. <link linkend="GimpUnit">GimpUnit</link>    <link linkend="gimp-unit-menu-get-unit">gimp_unit_menu_get_unit</link>         (<link linkend="GimpUnitMenu">GimpUnitMenu</link> *gum);
  27.  
  28. </synopsis>
  29. </refsynopsisdiv>
  30.  
  31. <refsect1>
  32. <title>Object Hierarchy</title>
  33. <synopsis>
  34.  
  35.   <link linkend="GtkObject">GtkObject</link>
  36.    +----<link linkend="GtkWidget">GtkWidget</link>
  37.          +----<link linkend="GtkContainer">GtkContainer</link>
  38.                +----<link linkend="GtkBin">GtkBin</link>
  39.                      +----<link linkend="GtkButton">GtkButton</link>
  40.                            +----<link linkend="GtkOptionMenu">GtkOptionMenu</link>
  41.                                  +----GimpUnitMenu
  42. </synopsis>
  43.  
  44. </refsect1>
  45.  
  46.  
  47. <refsect1>
  48. <title>Signal Prototypes</title>
  49. <synopsis>
  50.  
  51. "<link linkend="GimpUnitMenu-unit-changed">unit-changed</link>"
  52.             void        user_function      (<link linkend="GimpUnitMenu">GimpUnitMenu</link> *gimpunitmenu,
  53.                                             <link linkend="gpointer">gpointer</link> user_data);
  54. </synopsis>
  55. </refsect1>
  56.  
  57.  
  58. <refsect1>
  59. <title>Description</title>
  60. <para>
  61. This widget provides a <link linkend="GtkOptionMenu">GtkOptionMenu</link> which contains a list of <link linkend="GimpUnit">GimpUnit</link>'s.
  62. </para>
  63. <para>
  64. You can specify the string that will be displayed for each unit by
  65. passing a printf-like <parameter>format</parameter> string to <link linkend="gimp-unit-menu-new">gimp_unit_menu_new</link>().
  66. </para>
  67. <para>
  68. The constructor also lets you choose if the menu should contain items
  69. for GIMP_UNIT_PIXEL, GIMP_UNIT_PERCENT and a "More..." item which will
  70. pop up a dialog for selecting user-defined units.
  71. </para>
  72. <para>
  73. Whenever the user selects a unit from the menu or the dialog, the
  74. "unit_changed" signal will be emitted.
  75. </para>
  76. </refsect1>
  77.  
  78. <refsect1>
  79. <title>Details</title>
  80. <refsect2>
  81. <title><anchor id="GimpUnitMenu-struct">struct GimpUnitMenu</title>
  82. <programlisting>struct GimpUnitMenu;</programlisting>
  83. <para>
  84.  
  85. </para></refsect2>
  86. <refsect2>
  87. <title><anchor id="GIMP-UNIT-MENU-CAPS">GIMP_UNIT_MENU()</title>
  88. <programlisting>#define GIMP_UNIT_MENU(obj)            (GTK_CHECK_CAST ((obj), GIMP_TYPE_UNIT_MENU, GimpUnitMenu))
  89. </programlisting>
  90. <para>
  91. Checks if the passed pointer is a pointer to a <link linkend="GimpUnitMenu">GimpUnitMenu</link> and
  92. performs the cast if valid.
  93. </para><informaltable pgwide=1 frame="none" role="params">
  94. <tgroup cols="2">
  95. <colspec colwidth="2*">
  96. <colspec colwidth="8*">
  97. <tbody>
  98. <row><entry align="right"><parameter>obj</parameter> :</entry>
  99. <entry>The pointer to cast.
  100.  
  101.  
  102. </entry></row>
  103. </tbody></tgroup></informaltable></refsect2>
  104. <refsect2>
  105. <title><anchor id="gimp-unit-menu-new">gimp_unit_menu_new ()</title>
  106. <programlisting><link linkend="GtkWidget">GtkWidget</link>*  gimp_unit_menu_new              (const <link linkend="gchar">gchar</link> *format,
  107.                                              <link linkend="GimpUnit">GimpUnit</link> unit,
  108.                                              <link linkend="gboolean">gboolean</link> show_pixels,
  109.                                              <link linkend="gboolean">gboolean</link> show_percent,
  110.                                              <link linkend="gboolean">gboolean</link> show_custom);</programlisting>
  111. <para>
  112. Creates a new <link linkend="GimpUnitMenu">GimpUnitMenu</link> widget.
  113. </para>
  114. <para>
  115. The <parameter>format</parameter> string supports the following percent expansions:</para>
  116. <para>
  117.  
  118. <informaltable pgwide=1 frame="none" role="enum">
  119. <tgroup cols="2"><colspec colwidth="1*"><colspec colwidth="8*">
  120. <tbody>
  121.  
  122. <row>
  123. <entry>% f</entry>
  124. <entry>Factor (how many units make up an inch)</entry>
  125. </row>
  126.  
  127. <row>
  128. <entry>% y</entry>
  129. <entry>Symbol (e.g. "''" for GIMP_UNIT_INCH)</entry>
  130. </row>
  131.  
  132. <row>
  133. <entry>% a</entry>
  134. <entry>Abbreviation</entry>
  135. </row>
  136.  
  137. <row>
  138. <entry>% s</entry>
  139. <entry>Singular</entry>
  140. </row>
  141.  
  142. <row>
  143. <entry>% p</entry>
  144. <entry>Plural</entry>
  145. </row>
  146.  
  147. <row>
  148. <entry>%%</entry>
  149. <entry>Literal percent</entry>
  150. </row>
  151.  
  152. </tbody></tgroup></informaltable>
  153.  
  154. </para><informaltable pgwide=1 frame="none" role="params">
  155. <tgroup cols="2">
  156. <colspec colwidth="2*">
  157. <colspec colwidth="8*">
  158. <tbody>
  159. <row><entry align="right"><parameter>format</parameter> :</entry>
  160. <entry> A printf-like format string which is used to create the unit
  161. strings.
  162. </entry></row>
  163. <row><entry align="right"><parameter>unit</parameter> :</entry>
  164. <entry> The initially selected unit.
  165. </entry></row>
  166. <row><entry align="right"><parameter>show_pixels</parameter> :</entry>
  167. <entry> <link linkend="TRUE-CAPS">TRUE</link> if the unit menu should contain an item for
  168. GIMP_UNIT_PIXEL.
  169. </entry></row>
  170. <row><entry align="right"><parameter>show_percent</parameter> :</entry>
  171. <entry> <link linkend="TRUE-CAPS">TRUE</link> in the unit menu should contain an item for
  172. GIMP_UNIT_PERCENT.
  173. </entry></row>
  174. <row><entry align="right"><parameter>show_custom</parameter> :</entry>
  175. <entry> <link linkend="TRUE-CAPS">TRUE</link> if the unit menu should contain a "More..." item for
  176. opening the user-defined-unit selection dialog.
  177. </entry></row>
  178. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A pointer to the new <link linkend="GimpUnitMenu">GimpUnitMenu</link> widget.
  179.  
  180. </entry></row>
  181. </tbody></tgroup></informaltable></refsect2>
  182. <refsect2>
  183. <title><anchor id="gimp-unit-menu-set-unit">gimp_unit_menu_set_unit ()</title>
  184. <programlisting>void        gimp_unit_menu_set_unit         (<link linkend="GimpUnitMenu">GimpUnitMenu</link> *gum,
  185.                                              <link linkend="GimpUnit">GimpUnit</link> unit);</programlisting>
  186. <para>
  187. Sets a new <link linkend="GimpUnit">GimpUnit</link> for the specified <link linkend="GimpUnitMenu">GimpUnitMenu</link>.</para>
  188. <para>
  189.  
  190. </para><informaltable pgwide=1 frame="none" role="params">
  191. <tgroup cols="2">
  192. <colspec colwidth="2*">
  193. <colspec colwidth="8*">
  194. <tbody>
  195. <row><entry align="right"><parameter>gum</parameter> :</entry>
  196. <entry> The unit menu you want to set the unit for.
  197. </entry></row>
  198. <row><entry align="right"><parameter>unit</parameter> :</entry>
  199. <entry> The new unit.
  200. </entry></row>
  201. </tbody></tgroup></informaltable></refsect2>
  202. <refsect2>
  203. <title><anchor id="gimp-unit-menu-get-unit">gimp_unit_menu_get_unit ()</title>
  204. <programlisting><link linkend="GimpUnit">GimpUnit</link>    gimp_unit_menu_get_unit         (<link linkend="GimpUnitMenu">GimpUnitMenu</link> *gum);</programlisting>
  205. <para>
  206. Returns the <link linkend="GimpUnit">GimpUnit</link> the user has selected from the <link linkend="GimpUnitMenu">GimpUnitMenu</link>.</para>
  207. <para>
  208.  
  209. </para><informaltable pgwide=1 frame="none" role="params">
  210. <tgroup cols="2">
  211. <colspec colwidth="2*">
  212. <colspec colwidth="8*">
  213. <tbody>
  214. <row><entry align="right"><parameter>gum</parameter> :</entry>
  215. <entry> The unit menu you want to know the unit of.
  216. </entry></row>
  217. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The unit the user has selected.
  218.  
  219. </entry></row>
  220. </tbody></tgroup></informaltable></refsect2>
  221.  
  222. </refsect1>
  223.  
  224. <refsect1>
  225. <title>Signals</title>
  226. <refsect2><title><anchor id="GimpUnitMenu-unit-changed">The "unit-changed" signal</title>
  227. <programlisting>void        user_function                  (<link linkend="GimpUnitMenu">GimpUnitMenu</link> *gimpunitmenu,
  228.                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
  229. <para>
  230. This signal is emitted whenever the user selects a <link linkend="GimpUnit">GimpUnit</link> from the
  231. <link linkend="GimpUnitMenu">GimpUnitMenu</link>.
  232. </para><informaltable pgwide=1 frame="none" role="params">
  233. <tgroup cols="2">
  234. <colspec colwidth="2*">
  235. <colspec colwidth="8*">
  236. <tbody>
  237. <row><entry align="right"><parameter>gimpunitmenu</parameter> :</entry>
  238. <entry>the object which received the signal.
  239.  
  240. </entry></row>
  241. <row><entry align="right"><parameter>user_data</parameter> :</entry>
  242. <entry>user data set when the signal handler was connected.</entry></row>
  243. </tbody></tgroup></informaltable></refsect2>
  244. </refsect1>
  245.  
  246.  
  247. <refsect1>
  248. <title>See Also</title>
  249. <para>
  250. <link linkend="GimpUnit">GimpUnit</link>
  251. </para>
  252. <para>
  253. <link linkend="GimpSizeEntry">GimpSizeEntry</link>
  254. </para>
  255. </refsect1>
  256.  
  257. </refentry>
  258.